home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_cvs.idb / usr / freeware / info / cvsclient.info-3.z / cvsclient.info-3
Encoding:
GNU Info File  |  1999-04-16  |  11.0 KB  |  258 lines
  1. This is Info file cvsclient.info, produced by Makeinfo version 1.67
  2. from the input file ./cvsclient.texi.
  3.  
  4. 
  5. File: cvsclient.info,  Node: Example,  Next: Requirements,  Prev: Text tags,  Up: Protocol
  6.  
  7. Example
  8. =======
  9.  
  10.    Here is an example; lines are prefixed by `C: ' to indicate the
  11. client sends them or `S: ' to indicate the server sends them.
  12.  
  13.    The client starts by connecting, sending the root, and completing the
  14. protocol negotiation.  In actual practice the lists of valid responses
  15. and requests would be longer.
  16.  
  17.      C: Root /u/cvsroot
  18.      C: Valid-responses ok error Checked-in M E
  19.      C: valid-requests
  20.      S: Valid-requests Root Directory Entry Modified Argument Argumentx ci co
  21.      S: ok
  22.      C: UseUnchanged
  23.  
  24.    The client wants to check out the `supermunger' module into a fresh
  25. working directory.  Therefore it first expands the `supermunger'
  26. module; this step would be omitted if the client was operating on a
  27. directory rather than a module.
  28.  
  29.      C: Argument supermunger
  30.      C: Directory .
  31.      C: /u/cvsroot
  32.      C: expand-modules
  33.  
  34.    The server replies that the `supermunger' module expands to the
  35. directory `supermunger' (the simplest case):
  36.  
  37.      S: Module-expansion supermunger
  38.      S: ok
  39.  
  40.    The client then proceeds to check out the directory.  The fact that
  41. it sends only a single `Directory' request which specifies `.' for the
  42. working directory means that there is not already a `supermunger'
  43. directory on the client.
  44.  
  45.      C: Argument -N
  46.      C: Argument supermunger
  47.      C: Directory .
  48.      C: /u/cvsroot
  49.      C: co
  50.  
  51.    The server replies with the requested files.  In this example, there
  52. is only one file, `mungeall.c'.  The `Clear-sticky' and
  53. `Clear-static-directory' requests are sent by the current
  54. implementation but they have no effect because the default is for those
  55. settings to be clear when a directory is newly created.
  56.  
  57.      S: Clear-sticky supermunger/
  58.      S: /u/cvsroot/supermunger/
  59.      S: Clear-static-directory supermunger/
  60.      S: /u/cvsroot/supermunger/
  61.      S: E cvs server: Updating supermunger
  62.      S: M U supermunger/mungeall.c
  63.      S: Created supermunger/
  64.      S: /u/cvsroot/supermunger/mungeall.c
  65.      S: /mungeall.c/1.1///
  66.      S: u=rw,g=r,o=r
  67.      S: 26
  68.      S: int mein () { abort (); }
  69.      S: ok
  70.  
  71.    The current client implementation would break the connection here
  72. and make a new connection for the next command.  However, the protocol
  73. allows it to keep the connection open and continue, which is what we
  74. show here.
  75.  
  76.    After the user modifies the file and instructs the client to check it
  77. back in.  The client sends arguments to specify the log message and file
  78. to check in:
  79.  
  80.      C: Argument -m
  81.      C: Argument Well, you see, it took me hours and hours to find
  82.      C: Argumentx this typo and I searched and searched and eventually
  83.      C: Argumentx had to ask John for help.
  84.      C: Argument mungeall.c
  85.  
  86.    It also sends information about the contents of the working
  87. directory, including the new contents of the modified file.  Note that
  88. the user has changed into the `supermunger' directory before executing
  89. this command; the top level directory is a user-visible concept because
  90. the server should print filenames in `M' and `E' responses relative to
  91. that directory.
  92.  
  93.      C: Directory .
  94.      C: /u/cvsroot/supermunger
  95.      C: Entry /mungeall.c/1.1///
  96.      C: Modified mungeall.c
  97.      C: u=rw,g=r,o=r
  98.      C: 26
  99.      C: int main () { abort (); }
  100.  
  101.    And finally, the client issues the checkin command (which makes use
  102. of the data just sent):
  103.  
  104.      C: ci
  105.  
  106.    And the server tells the client that the checkin succeeded:
  107.  
  108.      S: M Checking in mungeall.c;
  109.      S: E /u/cvsroot/supermunger/mungeall.c,v  <--  mungeall.c
  110.      S: E new revision: 1.2; previous revision: 1.1
  111.      S: E done
  112.      S: Mode u=rw,g=r,o=r
  113.      S: Checked-in ./
  114.      S: /u/cvsroot/supermunger/mungeall.c
  115.      S: /mungeall.c/1.2///
  116.      S: ok
  117.  
  118. 
  119. File: cvsclient.info,  Node: Requirements,  Next: Obsolete,  Prev: Example,  Up: Protocol
  120.  
  121. Required versus optional parts of the protocol
  122. ==============================================
  123.  
  124.    The following are part of every known implementation of the CVS
  125. protocol (except obsolete, pre-1.5, versions of CVS) and it is
  126. considered reasonable behavior to completely fail to work if you are
  127. connected with an implementation which attempts to not support them.
  128. Requests: `Root', `Valid-responses', `valid-requests', `Directory',
  129. `Entry', `Modified', `Unchanged', `Argument', `Argumentx', `ci', `co',
  130. `update'.  Responses: `ok', `error', `Valid-requests', `Checked-in',
  131. `Updated', `Merged', `Removed', `M', `E'.
  132.  
  133.    A server need not implement `Repository', but in order to
  134. interoperate with CVS 1.5 through 1.9 it must claim to implement it (in
  135. `Valid-requests').  The client will not actually send the request.
  136.  
  137. 
  138. File: cvsclient.info,  Node: Obsolete,  Prev: Requirements,  Up: Protocol
  139.  
  140. Obsolete protocol elements
  141. ==========================
  142.  
  143.    This section briefly describes protocol elements which are obsolete.
  144. There is no attempt to document them in full detail.
  145.  
  146.    There was a `Repository' request which was like `Directory' except
  147. it only provided REPOSITORY, and the local directory was assumed to be
  148. similarly named.
  149.  
  150.    If the `UseUnchanged' request was not sent, there was a `Lost'
  151. request which was sent to indicate that a file did not exist in the
  152. working directory, and the meaning of sending `Entries' without `Lost'
  153. or `Modified' was different.  All current clients (CVS 1.5 and later)
  154. will send `UseUnchanged' if it is supported.
  155.  
  156. 
  157. File: cvsclient.info,  Node: Protocol Notes,  Prev: Protocol,  Up: Top
  158.  
  159. Notes on the Protocol
  160. *********************
  161.  
  162.    A number of enhancements are possible.  Also see the file TODO in
  163. the CVS source distribution, which has further ideas concerning various
  164. aspects of CVS, some of which impact the protocol.
  165.  
  166.    * The `Modified' request could be speeded up by sending diffs rather
  167.      than entire files.  The client would need some way to keep the
  168.      version of the file which was originally checked out; probably
  169.      requiring the use of "cvs edit" in this case is the most sensible
  170.      course (the "cvs edit" could be handled by a package like VC for
  171.      emacs).  This would also allow local operation of `cvs diff'
  172.      without arguments.
  173.  
  174.    * The current procedure for `cvs update' is highly sub-optimal if
  175.      there are many modified files.  One possible alternative would be
  176.      to have the client send a first request without the contents of
  177.      every modified file, then have the server tell it what files it
  178.      needs.  Note the server needs to do the what-needs-to-be-updated
  179.      check twice (or more, if changes in the repository mean it has to
  180.      ask the client for more files), because it can't keep locks open
  181.      while waiting for the network.  Perhaps this whole thing is
  182.      irrelevant if there is a multisite capability (as noted in TODO),
  183.      and therefore the rcsmerge can be done with a repository which is
  184.      connected via a fast connection.
  185.  
  186.    * The fact that `pserver' requires an extra network turnaround in
  187.      order to perform authentication would be nice to avoid.  This
  188.      relates to the issue of reporting errors; probably the clean
  189.      solution is to defer the error until the client has issued a
  190.      request which expects a response.  To some extent this might
  191.      relate to the next item (in terms of how easy it is to skip a
  192.      whole bunch of requests until we get to one that expects a
  193.      response).  I know that the kerberos code doesn't wait in this
  194.      fashion, but that probably can cause network deadlocks and perhaps
  195.      future problems running over a transport which is more transaction
  196.      oriented than TCP.  On the other hand I'm not sure it is wise to
  197.      make the client conduct a lengthy upload only to find there is an
  198.      authentication failure.
  199.  
  200.    * The protocol uses an extra network turnaround for protocol
  201.      negotiation (`valid-requests').  It might be nice to avoid this by
  202.      having the client be able to send requests and tell the server to
  203.      ignore them if they are unrecognized (different requests could
  204.      produce a fatal error if unrecognized).  To do this there should
  205.      be a standard syntax for requests.  For example, perhaps all
  206.      future requests should be a single line, with mechanisms analogous
  207.      to `Argumentx', or several requests working together, to provide
  208.      greater amounts of information.  Or there might be a standard
  209.      mechanism for counted data (analogous to that used by `Modified')
  210.      or continuation lines (like a generalized `Argumentx').  It would
  211.      be useful to compare what HTTP is planning in this area; last I
  212.      looked they were contemplating something called Protocol Extension
  213.      Protocol but I haven't looked at the relevant IETF documents in
  214.      any detail.  Obviously, we want something as simple as possible
  215.      (but no simpler).
  216.  
  217.    * The scrambling algorithm in the CVS client and server actually
  218.      support more characters than those documented in *Note Password
  219.      scrambling::.  Someday we are going to either have to document
  220.      them all (but this is not as easy as it may look, see below), or
  221.      (gradually and with adequate process) phase out the support for
  222.      other characters in the CVS implementation.  This business of
  223.      having the feature partly undocumented isn't a desirable state
  224.      long-term.
  225.  
  226.      The problem with documenting other characters is that unless we
  227.      know what character set is in use, there is no way to make a
  228.      password portable from one system to another.  For example, a with
  229.      a circle on top might have different encodings in different
  230.      character sets.
  231.  
  232.      It *almost* works to say that the client picks an arbitrary,
  233.      unknown character set (indeed, having the CVS client know what
  234.      character set the user has in mind is a hard problem otherwise),
  235.      and scrambles according to a certain octet<->octet mapping.  There
  236.      are two problems with this.  One is that the protocol has no way
  237.      to transmit character 10 decimal (linefeed), and the current
  238.      server and clients have no way to handle 0 decimal (NUL).  This
  239.      may cause problems with certain multibyte character sets, in which
  240.      octets 10 and 0 will appear in the middle of other characters.
  241.      The other problem, which is more minor and possibly not worth
  242.      worrying about, is that someone can type a password on one system
  243.      and then go to another system which uses a different encoding for
  244.      the same characters, and have their password not work.
  245.  
  246.      The restriction to the ISO646 invariant subset is the best
  247.      approach for strings which are not particularly significant to
  248.      users.  Passwords are visible enough that this is somewhat
  249.      doubtful as applied here.  ISO646 does, however, have the virtue
  250.      (!?) of offending everyone.  It is easy to say "But the $ is right
  251.      on people's keyboards!  Surely we can't forbid that".  From a
  252.      human factors point of view, that makes quite a bit of sense.  The
  253.      contrary argument, of course, is that a with a circle on top, or
  254.      some of the characters poorly handled by Unicode, are on
  255.      *someone*'s keyboard.
  256.  
  257.  
  258.